Managing Loading, Error, and Empty States in Flutter

Loading, error, and empty states are important parts of building reliable Flutter applications. Whenever an application loads data from an API, database, Firebase, local storage, or another asynchronous source, the UI should clearly communicate what is happening.

A good application should not simply show a blank screen while data is loading or crash when a request fails. Instead, it should provide a clear experience for loading, successful data, empty results, and errors.

Flutter provides tools such as FutureBuilder, StreamBuilder, ChangeNotifier, and AsyncSnapshot that can be used to manage asynchronous UI states. Flutter's official documentation demonstrates using FutureBuilder to display loading, success, and error states for asynchronous operations. Flutter Async Widgets Documentation

1. What Are Loading, Error, and Empty States?

Loading, error, and empty states are different UI conditions that can occur while an application retrieves or processes data.

Flutter's networking examples use FutureBuilder to distinguish between successful data, errors, and a still-pending asynchronous operation. :contentReference[oaicite:0]{index=0}

2. Why State Management Is Important

When an application performs an asynchronous operation, the result is not immediately available. The UI needs to change as the operation progresses.

Initial State
     ↓
Loading
     ↓
API / Database Request
     ↓
 ┌───────────────┬───────────────┐
 ↓               ↓               ↓
Success         Empty           Error
 ↓               ↓               ↓
Show Data      Show Empty      Show Error
UI             UI              UI

Without proper state handling, users may see a blank screen, an infinite spinner, outdated information, or technical error messages.

3. The Four Common UI States

Loading State

The loading state tells the user that the application is currently performing an operation.

Center(
  child: CircularProgressIndicator(),
)

Success State

The success state displays the data returned by the operation.

ListView.builder(
  itemCount: users.length,
  itemBuilder: (context, index) {
    return ListTile(
      title: Text(users[index].name),
    );
  },
)

Empty State

An empty state means the request completed successfully but there is no useful data to display.

const Center(
  child: Text('No users found'),
)

Error State

An error state is displayed when the operation fails.

Center(
  child: Column(
    mainAxisSize: MainAxisSize.min,
    children: [
      const Text('Unable to load users'),
      ElevatedButton(
        onPressed: retry,
        child: const Text('Retry'),
      ),
    ],
  ),
)

4. Loading State in Flutter

A loading state should appear immediately when an asynchronous operation starts.

CircularProgressIndicator

const Center(
  child: CircularProgressIndicator(),
)

LinearProgressIndicator

const LinearProgressIndicator()

Loading Text

const Column(
  mainAxisSize: MainAxisSize.min,
  children: [
    CircularProgressIndicator(),
    SizedBox(height: 16),
    Text('Loading data...'),
  ],
)

5. Button Loading State

Buttons that perform API operations should usually indicate when the operation is in progress and prevent accidental repeated submissions.

ElevatedButton(
  onPressed: isLoading ? null : submitForm,
  child: isLoading
      ? const SizedBox(
          height: 20,
          width: 20,
          child: CircularProgressIndicator(),
        )
      : const Text('Submit'),
)

This pattern prevents the user from repeatedly triggering the same operation while the first request is still running.

6. Loading State with setState()

For smaller applications, loading can be managed using a Boolean variable and setState().

bool isLoading = false;

Future<void> loadData() async {
  setState(() {
    isLoading = true;
  });
  try {
    await fetchData();
  } finally {
    if (!mounted) return;
    setState(() {
      isLoading = false;
    });
  }
}

Flutter's state-management documentation also demonstrates maintaining an isLoading property and notifying the UI when that state changes. Flutter State Management Documentation

7. What Is an Error State?

An error state is displayed when an operation cannot complete successfully.

Common causes include:

• No internet connection


• Server failure


• Request timeout


• Invalid authentication


• Unauthorized access


• Resource not found


• Invalid JSON


• Unexpected API response


• Database failure


• Application-level exceptions

8. Displaying an Error Message

if (errorMessage != null) {
  return Center(
    child: Text(errorMessage!),
  );
}

Error messages should be understandable to normal users. Avoid exposing raw stack traces or technical implementation details.

Good Error Messages

• "Unable to load the data."


• "Please check your internet connection."


• "The server is temporarily unavailable."


• "Something went wrong. Please try again."

9. Error State with Retry Button

A retry button is useful when an error may be temporary.

Column(
  mainAxisSize: MainAxisSize.min,
  children: [
    const Text('Failed to load data'),
    const SizedBox(height: 12),
    ElevatedButton(
      onPressed: retry,
      child: const Text('Retry'),
    ),
  ],
)

The retry action should start a new request and return the UI to the loading state.

10. What Is an Empty State?

An empty state occurs when an operation completes successfully but there are no records to display.

For example, an API may return an empty list:

[]

This is not necessarily an error. The application should explain that there is currently no content.

if (users.isEmpty) {
  return const Center(
    child: Text('No users found'),
  );
}

11. Empty State Examples

12. Empty State with an Action

An empty state can provide an action that helps the user move forward.

Column(
  mainAxisSize: MainAxisSize.min,
  children: [
    const Icon(Icons.inbox_outlined, size: 50),
    const SizedBox(height: 12),
    const Text('No orders found'),
    const SizedBox(height: 12),
    ElevatedButton(
      onPressed: openProducts,
      child: const Text('Browse Products'),
    ),
  ],
)

13. Empty State vs Error State

It is important not to treat an empty response as an error.

14. Using FutureBuilder

FutureBuilder is one of the most useful Flutter widgets for managing UI based on a Future. It receives a Future and rebuilds the UI based on the latest asynchronous snapshot. :contentReference[oaicite:1]{index=1}

FutureBuilder<User>(
  future: futureUser,
  builder: (context, snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const CircularProgressIndicator();
    }

    if (snapshot.hasError) {
      return const Text('Unable to load user');
    }
    if (!snapshot.hasData) {
      return const Text('No user data available');
    }
    return Text(snapshot.data!.name);
  },
)

15. Understanding AsyncSnapshot

The builder function of FutureBuilder receives an AsyncSnapshot. The snapshot contains information about the current asynchronous operation.

16. ConnectionState

ConnectionState helps determine the current stage of an asynchronous operation.

17. Complete Loading, Error, and Empty Example

FutureBuilder<List<String>>(
  future: fetchUsers(),
  builder: (context, snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const Center(
        child: CircularProgressIndicator(),
      );
    }

    if (snapshot.hasError) {
      return Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            const Text('Unable to load users'),
            const SizedBox(height: 12),
            ElevatedButton(
              onPressed: retry,
              child: const Text('Retry'),
            ),
          ],
        ),
      );
    }
    final users = snapshot.data ?? [];
    if (users.isEmpty) {
      return const Center(
        child: Text('No users found'),
      );
    }
    return ListView.builder(
      itemCount: users.length,
      itemBuilder: (context, index) {
        return ListTile(
          title: Text(users[index]),
        );
      },
    );
  },
)

This creates four practical outcomes: loading while waiting, error when the Future fails, empty when the result contains no records, and success when data is available.

18. Creating a Reusable Loading Widget

Instead of repeating loading UI throughout an application, create a reusable widget.

class LoadingView extends StatelessWidget {
  const LoadingView({super.key});

  @override
  Widget build(BuildContext context) {
    return const Center(
      child: CircularProgressIndicator(),
    );
  }
}

Use it wherever loading is required:

const LoadingView()

19. Creating a Reusable Error Widget

class ErrorView extends StatelessWidget {
  final String message;
  final VoidCallback? onRetry;

  const ErrorView({
    super.key,
    required this.message,
    this.onRetry,
  });
  @override
  Widget build(BuildContext context) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          const Icon(Icons.error_outline, size: 48),
          const SizedBox(height: 12),
          Text(message),
          if (onRetry != null) ...[
            const SizedBox(height: 12),
            ElevatedButton(
              onPressed: onRetry,
              child: const Text('Retry'),
            ),
          ],
        ],
      ),
    );
  }
}

20. Creating a Reusable Empty Widget

class EmptyView extends StatelessWidget {
  final String message;

  const EmptyView({
    super.key,
    required this.message,
  });
  @override
  Widget build(BuildContext context) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          const Icon(Icons.inbox_outlined, size: 48),
          const SizedBox(height: 12),
          Text(message),
        ],
      ),
    );
  }
}

21. Using Reusable State Widgets

if (isLoading) {
  return const LoadingView();
}

if (errorMessage != null) {
  return ErrorView(
    message: errorMessage!,
    onRetry: loadData,
  );
}
if (items.isEmpty) {
  return const EmptyView(
    message: 'No items found',
  );
}
return ItemList(items: items);

This approach keeps screen code clean and makes the application's state UI consistent.

22. Managing State with an Enum

For larger screens, multiple Boolean variables can become difficult to manage. An enum can represent the current state more clearly.

enum ViewState {
  initial,
  loading,
  success,
  empty,
  error,
}

Maintain the current state:

ViewState state = ViewState.initial;

Update the state while loading data:

Future<void> loadUsers() async {
  setState(() {
    state = ViewState.loading;
  });

  try {
    final result = await fetchUsers();
    if (!mounted) return;
    setState(() {
      users = result;
      state = result.isEmpty
          ? ViewState.empty
          : ViewState.success;
    });
  } catch (e) {
    if (!mounted) return;
    setState(() {
      state = ViewState.error;
    });
  }
}

23. Building UI from an Enum State

Widget buildContent() {
  switch (state) {
    case ViewState.initial:
      return const Text('Start loading data');

    case ViewState.loading:
      return const LoadingView();
    case ViewState.success:
      return UserList(users: users);
    case ViewState.empty:
      return const EmptyView(
        message: 'No users found',
      );
    case ViewState.error:
      return ErrorView(
        message: 'Failed to load users',
        onRetry: loadUsers,
      );
  }
}

24. Loading State with ChangeNotifier

For larger applications, state can be moved out of the widget and into a ViewModel or other state-management layer.

class UserViewModel extends ChangeNotifier {
  bool isLoading = false;
  String? error;
  List<User> users = [];

  Future<void> loadUsers() async {
    isLoading = true;
    error = null;
    notifyListeners();
    try {
      users = await fetchUsers();
    } catch (e) {
      error = 'Failed to load users';
    } finally {
      isLoading = false;
      notifyListeners();
    }
  }
}

Flutter's official state-management tutorial demonstrates a similar approach using ChangeNotifier, an isLoading property, an error value, and notifyListeners() to update the UI. :contentReference[oaicite:2]{index=2}

25. Handling Success, Empty, and Error in a ViewModel

class UserViewModel extends ChangeNotifier {
  bool isLoading = false;
  String? error;
  List<User> users = [];

  Future<void> loadUsers() async {
    isLoading = true;
    error = null;
    notifyListeners();
    try {
      final result = await fetchUsers();
      users = result;
    } catch (e) {
      error = 'Unable to load users';
      users = [];
    } finally {
      isLoading = false;
      notifyListeners();
    }
  }
}

The UI can then determine whether to display loading, error, empty, or success content based on the ViewModel state.

26. Avoiding Infinite Loading

An application should never remain in a loading state forever. Every asynchronous operation should have a clear completion path.

try {
  setState(() {
    isLoading = true;
  });

  await fetchData();
} catch (e) {
  setState(() {
    errorMessage = 'Request failed';
  });
} finally {
  if (!mounted) return;
  setState(() {
    isLoading = false;
  });
}

The finally block ensures that the loading state is cleared even when an exception occurs.

27. Handling API Status Codes

When loading data from an API, check the HTTP response before treating the operation as successful.

final response = await http.get(
  Uri.parse('https://example.com/users'),
);

if (response.statusCode == 200) {
  // Success
} else {
  throw Exception('Failed to load users');
}

Flutter's networking documentation recommends checking the expected response status and throwing an exception when the response does not meet the expected condition. :contentReference[oaicite:3]{index=3}

28. Handling Network Errors

try {
  final users = await fetchUsers();

  setState(() {
    this.users = users;
  });
} catch (e) {
  setState(() {
    errorMessage = 'Please check your internet connection';
  });
}

The user should receive a meaningful message instead of a raw exception.

29. Handling Timeout States

A network request can be given a maximum waiting time.

final response = await http
    .get(Uri.parse('https://example.com/users'))
    .timeout(
      const Duration(seconds: 10),
    );

If the request takes too long, the application can move from loading to an error state and offer a retry action.

30. Retry Mechanism

A retry mechanism allows users to repeat a failed operation without leaving the current screen.

void retry() {
  setState(() {
    futureUsers = fetchUsers();
  });
}

Connect it to a button:

ElevatedButton(
  onPressed: retry,
  child: const Text('Try Again'),
)

31. Pull-to-Refresh

For lists, RefreshIndicator can provide a pull-to-refresh experience.

RefreshIndicator(
  onRefresh: () async {
    await loadUsers();
  },
  child: ListView.builder(
    itemCount: users.length,
    itemBuilder: (context, index) {
      return ListTile(
        title: Text(users[index].name),
      );
    },
  ),
)

32. Keeping Existing Data During Refresh

During a refresh, it is often better to keep the existing content visible rather than replacing the entire screen with a loading spinner.

Column(
  children: [
    if (isRefreshing)
      const LinearProgressIndicator(),
    Expanded(
      child: UserList(users: users),
    ),
  ],
)

This provides feedback while preserving the information the user is already viewing.

33. Skeleton Loading

A skeleton loader displays placeholder shapes while content is being loaded.

Column(
  children: [
    Container(
      height: 20,
      width: 200,
      color: Colors.grey.shade300,
    ),
    const SizedBox(height: 10),
    Container(
      height: 15,
      width: double.infinity,
      color: Colors.grey.shade300,
    ),
  ],
)

Skeleton loading can be useful for content-heavy applications because the user can see the approximate structure of the upcoming content.

34. Error Handling with SnackBar

A SnackBar is useful for short-lived errors that do not require replacing the complete screen.

ScaffoldMessenger.of(context).showSnackBar(
  const SnackBar(
    content: Text('Unable to connect to the server'),
  ),
);

35. Error Handling with Dialog

A dialog can be used when the user must acknowledge an important error.

showDialog(
  context: context,
  builder: (context) {
    return AlertDialog(
      title: const Text('Error'),
      content: const Text(
        'Unable to complete the request.',
      ),
      actions: [
        TextButton(
          onPressed: () {
            Navigator.pop(context);
          },
          child: const Text('OK'),
        ),
      ],
    );
  },
);

36. Do Not Put API Calls Directly Inside build()

API calls should generally not be created directly inside the build() method because Flutter can call build() many times.

Incorrect:

@override
Widget build(BuildContext context) {
  return FutureBuilder(
    future: fetchUsers(),
    builder: (context, snapshot) {
      return Container();
    },
  );
}

A better approach is to create and store the Future in state.

late Future<List<User>> futureUsers;

@override
void initState() {
  super.initState();
  futureUsers = fetchUsers();
}

Flutter's official fetch-data recipe specifically recommends storing the Future in state and initializing it in initState() rather than repeatedly creating the Future in build(). :contentReference[oaicite:4]{index=4}

37. Handling mounted After Async Operations

After an asynchronous operation completes, the widget may no longer be part of the widget tree. Check mounted before calling setState().

final result = await fetchUsers();

if (!mounted) return;
setState(() {
  users = result;
});

This prevents attempting to update a State object that is no longer active.

38. Complete Practical Example

import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

class User {
  final int id;
  final String name;
  final String email;
  User({
    required this.id,
    required this.name,
    required this.email,
  });
  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
      email: json['email'],
    );
  }
}
Future<List<User>> fetchUsers() async {
  final response = await http.get(
    Uri.parse('https://jsonplaceholder.typicode.com/users'),
  );
  if (response.statusCode != 200) {
    throw Exception('Failed to load users');
  }
  final data = jsonDecode(response.body) as List;
  return data
      .map(
        (json) => User.fromJson(
          json as Map<String, dynamic>,
        ),
      )
      .toList();
}
class UserScreen extends StatefulWidget {
  const UserScreen({super.key});
  @override
  State<UserScreen> createState() => _UserScreenState();
}
class _UserScreenState extends State<UserScreen> {
  late Future<List<User>> futureUsers;
  @override
  void initState() {
    super.initState();
    futureUsers = fetchUsers();
  }
  void retry() {
    setState(() {
      futureUsers = fetchUsers();
    });
  }
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Users'),
      ),
      body: FutureBuilder<List<User>>(
        future: futureUsers,
        builder: (context, snapshot) {
          if (snapshot.connectionState ==
              ConnectionState.waiting) {
            return const Center(
              child: CircularProgressIndicator(),
            );
          }
          if (snapshot.hasError) {
            return Center(
              child: Column(
                mainAxisSize: MainAxisSize.min,
                children: [
                  const Text(
                    'Unable to load users',
                  ),
                  const SizedBox(height: 12),
                  ElevatedButton(
                    onPressed: retry,
                    child: const Text('Retry'),
                  ),
                ],
              ),
            );
          }
          final users = snapshot.data ?? [];
          if (users.isEmpty) {
            return const Center(
              child: Text('No users found'),
            );
          }
          return ListView.builder(
            itemCount: users.length,
            itemBuilder: (context, index) {
              final user = users[index];
              return ListTile(
                leading: CircleAvatar(
                  child: Text(
                    user.name.substring(0, 1),
                  ),
                ),
                title: Text(user.name),
                subtitle: Text(user.email),
              );
            },
          );
        },
      ),
    );
  }
}

39. State Flow of the Practical Example

User opens UserScreen
        ↓
initState()
        ↓
fetchUsers()
        ↓
Loading State
        ↓
Check API Response
        ↓
 ┌──────────────┬───────────────┐
 ↓              ↓               ↓
Success        Empty           Error
 ↓              ↓               ↓
Users          No Users        Error Message
Displayed      Message         + Retry

40. State Management Architecture

For larger Flutter applications, loading, error, and empty states can be separated from the UI using a layered architecture.

Flutter UI
    ↓
ViewModel / State Management
    ↓
Repository
    ↓
API Service
    ↓
HTTP Client
    ↓
Backend API

Flutter's architecture documentation describes separating UI state from data access through patterns such as ViewModels and repositories, helping keep UI state changes organized. Flutter UI Architecture Documentation

41. Generic UI State Class

A generic state class can represent different outcomes in a reusable way.

enum ApiStatus {
  initial,
  loading,
  success,
  empty,
  error,
}

Maintain additional data when required:

class ApiState<T> {
  final ApiStatus status;
  final T? data;
  final String? error;

  const ApiState({
    required this.status,
    this.data,
    this.error,
  });
}

42. Handling Multiple Loading States

Some screens may have more than one type of loading operation.

These states should not always replace the entire screen. For example, pagination can display a small progress indicator at the bottom while keeping existing records visible.

43. Pagination Loading State

ListView.builder(
  itemCount: users.length + 1,
  itemBuilder: (context, index) {
    if (index == users.length) {
      return isLoadingMore
          ? const Padding(
              padding: EdgeInsets.all(16),
              child: Center(
                child: CircularProgressIndicator(),
              ),
            )
          : const SizedBox.shrink();
    }

    return ListTile(
      title: Text(users[index].name),
    );
  },
)

44. Avoiding Duplicate Requests

When loading or submitting data, prevent multiple requests from being started accidentally.

if (isLoading) {
  return;
}

setState(() {
  isLoading = true;
});

Disable the corresponding button:

ElevatedButton(
  onPressed: isLoading ? null : submit,
  child: Text(
    isLoading ? 'Please wait...' : 'Submit',
  ),
)

45. User-Friendly Error Messages

Technical exceptions are useful for developers but should usually be converted into meaningful messages for users.

46. Common Mistakes

Mistake 1: No Loading State

Users may think the application is frozen.

Mistake 2: Treating Empty Data as an Error

An empty list can be a valid successful response.

Mistake 3: No Retry Option

Users may have no way to recover from a temporary network failure.

Mistake 4: Calling APIs Inside build()

Repeated rebuilds can cause unnecessary requests. Store the Future or manage the request through a suitable state layer.

Mistake 5: Infinite Loading

Make sure every request can transition from loading to success, empty, or error.

Mistake 6: Showing Raw Exceptions

Technical exception details are usually not appropriate for normal users.

Mistake 7: Duplicate Requests

Disable buttons or guard requests while an operation is already running.

Mistake 8: Updating an Unmounted Widget

Use mounted checks after asynchronous operations when updating widget state.

47. Best Practices

• Always provide a visible loading state.


• Clearly separate loading, success, empty, and error states.


• Do not treat an empty result as a network error.


• Provide retry actions for recoverable errors.


• Use user-friendly error messages.


• Check API response status codes.


• Handle timeout and network exceptions.


• Prevent duplicate requests.


• Avoid creating API Futures repeatedly inside build().


• Use mounted when appropriate after asynchronous operations.


• Keep existing data visible during refresh when appropriate.


• Use skeleton loaders when they improve the user experience.


• Use reusable loading, error, and empty widgets.


• Use enums or dedicated state classes for complex screens.


• Separate API services from UI code.


• Use a repository or ViewModel architecture for larger applications.

48. Practical Mini Project

Create a Flutter user-management screen with the following requirements:

1. Fetch users from an API.


2. Display a loading indicator while the request is running.


3. Display users when the request succeeds.


4. Display an empty state when the API returns an empty list.


5. Display an error state when the request fails.


6. Add a Retry button.


7. Add pull-to-refresh.


8. Prevent duplicate requests.


9. Show a small loading indicator while loading additional pages.


10. Display user-friendly error messages.

Expected Flow

Open Screen
    ↓
Loading
    ↓
API Request
    ↓
Check Response
    ↓
 ┌───────────┬───────────┬───────────┐
 ↓           ↓           ↓
Success     Empty       Error
 ↓           ↓           ↓
Show Data   Empty UI    Error UI
                         ↓
                       Retry
                         ↓
                      Loading

49. Interview Questions

1. What is a loading state in Flutter?


2. Why are loading states important?


3. What is an error state?


4. What is an empty state?


5. What is the difference between an empty state and an error state?


6. How can you show a loading indicator in Flutter?


7. What is FutureBuilder?


8. What is AsyncSnapshot?


9. What is ConnectionState.waiting?


10. How do you display an error using FutureBuilder?


11. How can you implement a Retry button?


12. Why should API calls generally not be placed directly inside build()?


13. How can you prevent duplicate API requests?


14. What is the purpose of mounted?


15. How can an enum be used for UI states?


16. How can loading and error states be managed with ChangeNotifier?


17. Why should technical exceptions not always be displayed directly to users?


18. What is the purpose of a skeleton loader?


19. How can pull-to-refresh be implemented?


20. How should loading, error, and empty states be organized in a large Flutter application?

50. Quick Revision

51. Useful Resources

• Flutter Async Widgets


• Flutter: Fetch Data from the Internet


• Flutter: Send Data to the Internet


• Flutter State Management with ChangeNotifier


• Flutter UI Architecture

52. Learn Flutter with JustAcademy

For structured Flutter learning, practical development, projects, and course guidance, explore the following resources:

JustAcademy Flutter Training Course

Register for Flutter Course Demo

Conclusion

Managing loading, error, and empty states is an essential part of creating professional Flutter applications. A good screen should clearly communicate what is happening at every stage of an asynchronous operation. Loading states inform users that work is in progress, success states display useful data, empty states explain that there is currently nothing to show, and error states provide clear information and recovery actions.

Flutter provides several tools for implementing these patterns, including FutureBuilder, AsyncSnapshot, setState(), ChangeNotifier, and custom state models. By separating API logic from UI code, preventing duplicate requests, providing retry functionality, handling timeouts, and using reusable state widgets, developers can create applications that remain responsive, predictable, and user-friendly even when data is unavailable or a request fails.